/**
 * Created on 23.03.2012
 */
package com.example.ejb;

import java.util.List;

import javax.ejb.Local;

import com.example.ejb.exceptions.DatabaseException;
import com.example.ejb.exceptions.UserAlreadyExistsException;
import com.example.ejb.exceptions.UserDoesNotExistException;
import com.example.ejb.model.DbUser;

/**
 * @author Ciprian Mihalache
 *
 */
@Local
public interface UsersConnection {
	String JNDI_NAME = "UsersConnection";

	/**
	 * For retrieving all users
	 * 
	 * @return all users from database
	 */
	List<DbUser> getAllUsers();

	/**
	 * Method used for retrieving the {@link DbUser} object with the specified database
	 * id.
	 *
	 * @param userDbId
	 *            the database id of the desired {@link DbUser}
	 * @return the corresponding {@link DbUser} or null in case there is no {@link DbUser}
	 *         in database with the specified Id
	 * @throws DatabaseException
	 *             in case something goes wrong with the database communication
	 */
	DbUser getUserByDbId(long userDbId) throws DatabaseException;

	/**
	 * Method used for adding a new user. In case you need to persist the changes of an
	 * existing user, please use {@link #updateUser(DbUser)} method.
	 *
	 * @param user
	 *            an {@link DbUser} which was never persisted
	 * @throws IllegalArgumentException
	 *             in case the user is null
	 * @throws UserAlreadyExistsException
	 *             in case the provided user has a valid database ID
	 * @throws DatabaseException
	 *             in case something goes wrong with the persistence process
	 */
	void addUser(DbUser user) throws UserAlreadyExistsException, DatabaseException;

	/**
	 * Method used for updating an existing user. In case you need to add a new user,
	 * please use {@link #addUser(DbUser)} method.
	 *
	 * @param user
	 *            an {@link DbUser} which was persisted
	 * @throws IllegalArgumentException
	 *             in case the user is null
	 * @throws UserDoesNotExistException
	 *             in case the provided user doesn't have a database ID
	 * @throws DatabaseException
	 *             in case something goes wrong with the persistence process
	 */
	void updateUser(DbUser user) throws UserDoesNotExistException, DatabaseException;

	/**
	 * Method used for deleting an existing user.
	 *
	 * @param userDbId
	 *            the database id of the user which is required to be deleted
	 * @throws IllegalArgumentException
	 *             in case the userDbId is not strictly positive
	 * @throws UserDoesNotExistException
	 *             in case there is no user with the specified database id
	 * @throws DatabaseException
	 *             in case something goes wrong with the persistence process
	 */
	void deleteUser(long userDbId) throws UserDoesNotExistException, DatabaseException;
}
